Interrupt 21h Function 714Eh
Searches a
directory for the first file or directory whose name and attributes match the
specified name and attributes.
mov ax, 714Eh ; Find First File
mov ch, MustMatchAttrs ; see below
mov cl, SearchAttrs ; see below
mov dx, seg Filename ; see below
mov ds, dx
mov dx, offset Filename
mov di, seg FindData ; see below
mov es, di
mov di, offset FindData
mov si, DateTimeFormat ; see below
int 21h
jc error
mov [Handle], ax ; search handle
mov [ConversionCode], cx ; Unicode to OEM/ANSI conversion OK?
Parameters
MustMatchAttrs
Additional
filter on the attributes specified in SearchAttrs. This parameter can be
a combination of these values:
|
_A_NORMAL
(0000h) |
|
|
|
|
The file
can be read from or written to. This value is valid only if used alone. |
|
|
_A_RDONLY
(0001h) |
|
|
|
|
The file
can be read from, but not written to. |
|
|
_A_HIDDEN
(0002h) |
|
|
|
|
The file is
hidden and does not appear in an ordinary directory listing. |
|
|
_A_SYSTEM
(0004h) |
|
|
|
|
The file is
part of the operating system or is used exclusively by it. |
|
|
_A_VOLID
(0008h) |
|
|
|
|
The name
specified by Filename is used as the volume label for the current
medium. |
|
|
_A_SUBDIR
(0010h) |
|
|
|
|
The name
specified by Filename is used as a directory, not a file. |
|
|
_A_ARCH
(0020h) |
|
|
|
|
The file is
an archive file. Applications use this value to mark files for backup or
removal. |
|
SearchAttrs
File
attributes to search for. This parameter can be a combination of these values:
|
_A_NORMAL
(0000h) |
|
_A_RDONLY
(0001h) |
|
_A_HIDDEN
(0002h) |
|
_A_SYSTEM
(0004h) |
|
_A_VOLID
(0008h) |
|
_A_SUBDIR
(0010h) |
|
_A_ARCH
(0020h) |
Filename
Address of a
null-terminated string specifying the name of the file or directory to search
for. The name, which must be a valid filename or directory name, can include
the * and ? wildcard
characters. Long filenames are allowed.
FindData
Address of a WIN32_FIND_DATA structure that receives
information about the file.
DateTimeFormat
Date and time
format to be returned. This parameter must be one of these values:
|
0 |
Returns the
date and time in 64-bit file time format. |
|
1 |
Returns the
MS-DOS date and time values. MS-DOS date and time values are returned in the
low doubleword of the FILETIME structure. Within the doubleword, the date is returned
in the high-order word; the time is in the low-order word. |
Return Value
Clears the
carry flag, copies information about the file to the specified buffer, returns
the search handle in the AX register, and sets the CX register to a combination
of the following values if successful:
|
0x0000 |
All
characters in the primary and alternate name members in the structure
specified by FindData were successfully converted from Unicode. |
|
0x0001 |
The primary
name returned in the structure specified by FindData contains
underscore characters in place of characters that could not be converted from
Unicode. |
|
0x0002 |
The
alternate name returned in the structure specified by FindData contains
underscore characters in place of characters that could not be converted from
Unicode. |
Otherwise,
the function sets the carry flag and sets the AX register to an error value.
Remarks
Find First
File and subsequent calls to Find Next File (Interrupt 21h Function 714Fh) use the following algorithm
to match the attributes of a file or directory (referred to as Attributes in
the algorithm) against MustMatchAttrs and SearchAttrs.
if
((((<MustMatchAttrs> & ~<Attributes>) & 0x3F) == 0)
&& (((~<SearchAttrs>
& <Attributes>) & 0x1E) == 0))
{
return the file or directory
name
}
else
{
continue searching for the next
name
}
The following
table lists the MustMatchAttrs and SearchAttrs values for some
common searches where the specified filename is *.* . In the table, the word normal means that the read
only, hidden, or system attributes have not been set. Parentheses are used to
indicate that a file or directory has more than one attribute. For example,
(hidden and system) indicates that a file or directory has both the hidden
attribute and the system attribute.
|
MustMatchAttrs |
SearchAttrs |
Find
results |
|
10h |
10h |
All normal
directories |
|
10h |
12h |
All normal
and hidden directories |
|
10h |
14h |
All normal
and system directories |
|
10h |
16h |
All normal,
hidden, system and (hidden and system) directories |
|
12h |
12h |
All hidden
directories |
|
14h |
14h |
All system
directories |
|
16h |
16h |
All (hidden
and system) directories |
|
00h |
00h |
All normal
files |
|
00h |
01h |
All normal
and read only files |
|
00h |
02h |
All normal
and hidden files |
|
00h |
04h |
All normal
and system files |
|
00h |
06h |
All normal,
hidden, system, and (hidden and system) files |
|
00h |
10h |
All normal
files and directories |
|
01h |
01h |
All read
only files |
|
02h |
02h |
All hidden
files |
|
02h |
06h |
All hidden
and (hidden and system) files |
This function
can be used to return the volume label by specifying only _A_VOLID (0008h) in
both MustMatchAttrs and SearchAttrs.
An
application may use the handle returned in the AX register in subsequent calls
to Find Next File (Interrupt 21h Function 714Fh308B9YP). It is important to close the handle when it
is no longer needed by calling Find Close (Interrupt 21h Function 71A1h).
Wildcard
searches are more flexible in Windows 95 than in MS-DOS. For example, *1
finds the filenames (both long filenames and aliases) that end in a 1,
and *mid* finds filenames that contain the characters mid. In
MS-DOS and in Windows 95 searching on real-mode FAT directories, all characters
after the first * are ignored.